---
title: Mocking
description: Mock your GraphQL data based on a schema.
---

import TopLevelAwait from "../shared/top-level-await.mdx"

> 📣 **New since Apollo Server 4:** Unlike previous versions, mocking is [no longer built in to Apollo Server](../migration/#mocks-and-mockentireschema). This article teaches you how to use the third-party `@graphql-tools` package to mock data for Apollo Server. For the most up-to-date information on `@graphql-tools`, we recommend referencing [their documentation](https://www.graphql-tools.com/docs/mocking).

Mocking enables Apollo Server to return simulated data for GraphQL operations based on your server's schema. The strongly-typed nature of a GraphQL API lends itself to mocking, which is an important part of a GraphQL-first development process.

Mocking enables frontend developers to build out and test UI components and features without needing to wait for a full backend implementation. Mocking is also valuable when using a UI tool like [Storybook](https://storybook.js.org/), because you don't need to start a real GraphQL server.

## Enabling mocks

To mock data based on your schema start by installing the [`@graphql-tools/mock`](https://www.graphql-tools.com/docs/mocking) and [`@graphql-tools/schema`](https://www.graphql-tools.com/docs/generate-schema#makeexecutableschemaoptions) packages into your dev dependencies:

```bash
  npm install --save-dev @graphql-tools/mock @graphql-tools/schema
```

You can combine `addMocksToSchema` (from `@graphql-tools/mock`) and `makeExecutableSchema` (from `@graphql-tools/schema`) to provide mock data for every field in your server's schema:

<MultiCodeBlock>

```ts
import { ApolloServer } from '@apollo/server';
import { addMocksToSchema } from '@graphql-tools/mock';
import { makeExecutableSchema } from '@graphql-tools/schema';
import { typeDefs } from './schema';
import { resolvers } from './resolvers';

new ApolloServer({
  // addMocksToSchema accepts a schema instance and provides
  // mocked data for each field in the schema
  // highlight-start
  schema: addMocksToSchema({
    schema: makeExecutableSchema({ typeDefs, resolvers }),
  }),
  // highlight-end
});
```

</MultiCodeBlock>

Mocking logic looks at the type returned by each schema field and returns a default value for that type.

The table below covers the default scalar types and the default mocked values returned for each type:

<table class="field-table">
  <thead>
    <tr>
      <th>Type</th>
      <th>Default Mock Value</th>
    </tr>
  </thead>

<tbody>
<tr >
<td>

###### `Int`

</td>
<td>

Returns a random positive or negative integer.

</td>
</tr>

<tr>
<td>

###### `String`

</td>
<td>

Returns `Hello world`.

</td>
</tr>

<tr>
<td>

###### `Float`

</td>
<td>

Returns a random positive or negative double-precision floating-point value.

</td>
</tr>

<tr>
<td>

###### `Boolean`

</td>
<td>

Randomly returns either `true` or `false`.

</td>
</tr>

<tr>
<td>

###### `ID`

</td>
<td>

Returns a randomized UUID containing a combination of integers and letters.

</td>
</tr>

</tbody>
</table>

When using mocks, you don't have to specify `resolvers`. By default, any `resolvers` you specify are **ignored** when you enable `mocks`. To configure this behavior, see [Using existing resolvers with mocks](#using-existing-resolvers-with-mocks).

> Note: If `typeDefs` has any [custom scalar types](../schema/custom-scalars/#providing-custom-scalars-to-apollo-server), you will need to specify what your server should return for those types. You can do this by creating a customized mock with resolvers for each custom scalar type, as described below.

## Customizing mocks

<TopLevelAwait />

For more sophisticated testing, you can customize your mocks to return user-specified data. You can customize your mocks by providing an object that specifies the values to return for different return types.

By default, the functions you define in your `mocks` take precedence over any currently defined resolvers.

For example, below, both `Query.hello` and `Query.resolved` return `Hello`:

<MultiCodeBlock>

```ts
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { addMocksToSchema } from '@graphql-tools/mock';
import { makeExecutableSchema } from '@graphql-tools/schema';

const typeDefs = `#graphql
  type Query {
    hello: String
    resolved: String
  }
`;

const resolvers = {
  Query: {
    resolved: () => 'Resolved',
  },
};

// highlight-start
const mocks = {
  Int: () => 6,
  Float: () => 22.1,
  String: () => 'Hello',
};
// highlight-end

const server = new ApolloServer({
  schema: addMocksToSchema({
    schema: makeExecutableSchema({ typeDefs, resolvers }),
    mocks, // highlight-line
  }),
});

const { url } = await startStandaloneServer(server, { listen: { port: 4000 } });

console.log(`🚀 Server listening at: ${url}`);
```

</MultiCodeBlock>

You can also use `mocks` to define object types and the fields belonging to those object types (much like a [resolver map](../data/resolvers/#base-syntax)). In the below example, our mocked `Person` object calls a function returning an object with fields that contain _other_ functions:

<MultiCodeBlock>

```ts
// importing the casual library
const casual = require('casual');

const mocks = {
  Person: () => ({
    name: casual.name,
    age: () => casual.integer(0, 120),
  }),
};
```

</MultiCodeBlock>

This example uses [casual](https://github.com/boo1ean/casual), a fake data generator for JavaScript that returns a different result every time the function is called. In other scenarios, such as testing, a collection of fake objects or a generator that always uses a consistent seed are often necessary to provide consistent data.

### Using lists in mocks

To automate mocking a list, return an array of the desired length. Using `[...new Array(n)]` is convenient syntax for creating an array that contains _n_ copies of `undefined`.

<MultiCodeBlock>

```ts
import casual from 'casual';

const mocks = {
  Person: () => ({
    // a list of length between 2 and 6, using the "casual" npm module
    // to generate a random integer
    friends: [...new Array(casual.integer(2, 6))],
    // a list of three lists of two items: [[1, 1], [2, 2], [3, 3]]
    listOfLists: () => [...new Array(3)].map((i) => [...new Array(2)]),
  }),
};
```

</MultiCodeBlock>

### Using existing resolvers with mocks

By default, mocks overwrite your server's existing resolvers. To use your server's resolvers while mocking, set the `makeExecutableSchema` function's `preserveResolvers` option to `true`:

<MultiCodeBlock>

```ts
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { addMocksToSchema } from '@graphql-tools/mock';
import { makeExecutableSchema } from '@graphql-tools/schema';

const typeDefs = `#graphql
  type Query {
    hello: String
    resolved: String
  }
`;

const resolvers = {
  Query: {
    resolved: () => 'Resolved',
  },
};

const mocks = {
  Int: () => 6,
  Float: () => 22.1,
  String: () => 'Hello',
};

const server = new ApolloServer({
  schema: addMocksToSchema({
    schema: makeExecutableSchema({ typeDefs, resolvers }),
    mocks,
    preserveResolvers: true, // highlight-line
  }),
});

const { url } = await startStandaloneServer(server, { listen: { port: 4000 } });

console.log(`🚀 Server listening at: ${url}`);
```

</MultiCodeBlock>

Above, the `resolved` query now uses its defined resolver, so it returns the string `Resolved`.
